home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / NEWSOFT / AUGUST / FREENET2 / !FreeNet / Docs / Resolver < prev    next >
Text File  |  1996-10-13  |  8KB  |  264 lines
  1. INetDB - Cacheing Resolver
  2. --------------------------
  3.  
  4.    Copyright (c) 1994 Adam Goodfellow
  5.  
  6. This software is in part based upon source that is 
  7.  
  8.    Copyright (c) 1985, 1988 Regents of the University of California.
  9.    All rights reserved.
  10.   
  11.  
  12. Introduction
  13. ============
  14.  
  15. The basic Acorn and FreeNet TCP/IP stacks allows names of hosts with which
  16. you want to communicate to be kept in a local file to save you having to
  17. remember the numeric IP address for each host. For small networks this is
  18. generally quite acceptable.
  19.  
  20. However, for larger networks and especially the Internet, keeping the
  21. hosts file upto date can be very time consuming, if not impossible.
  22.  
  23. To get round this problem, it is normal for one or more machines on a
  24. network to provide host name and IP address databases that are
  25. accessable on a single machine.
  26.  
  27. In actual fact, with very large networks, this database (Domain Name
  28. System or DNS) is distributed amongst a number of machines (called
  29. name-servers), each being responsible for pursuing information about
  30. other networks (domains) on behalf of hosts on its local network (in its
  31. local domain), and answering secific queries about its local network
  32. (domain) from systems on other networks (in other domains).
  33.  
  34. The Resolver provided as part of the INetDB module performs the task of
  35. communicating with nameservers on behalf of many applications written
  36. for the FreeNet and/or Acorn TCP/IP stacks.
  37.  
  38. Normally, as the name-server is a machine connected to your local
  39. network, the time taken to get a reply from a nameserver is quite short,
  40. a fraction of a second on a lightly loaded network and a lightly loaded
  41. name-server.
  42.  
  43. However with heavily loaded networks and nameservers, or if the query
  44. has to be sent over serial connection via a modem to a nameserver on the
  45. Internet, the time taken for the response can be quite long, especially
  46. with the recent upsurge in Internet use. Also, in circumstances of heavy
  47. network conjestion, additional queries caused by resending of requests
  48. that have been deemed lost further degrades network performance.
  49.  
  50. The obvious solution is to somehow reduce the dependancy upon the
  51. name-server for processing queries every time you make a connection to
  52. another named host.
  53.  
  54. This what sets this resolver apart from the types of resolver commonly
  55. found on desktop computers. It remembers information recently obtained
  56. from a name-server in a cache and so is often able to give an instant
  57. responce to a repeat of recent similar query, making it very appropriate
  58. for use where the nameserver is at the other end of a dial up connection
  59. via a modem.
  60.  
  61. The cacheing methods used are such that so long as the name-servers are
  62. providing accurate information about the life time of data retrieved,
  63. then the cache will only give upto date information, and will
  64. automatically remove information considered out of date, ensuring a
  65. fresh copy is read from the nameserver.
  66.   
  67.  
  68. Setting Up
  69. ==========
  70.  
  71. Resolver configuration is stored in the file "!FreeUser.Files.ResConf".
  72. Options in this file are as follows: (See example)
  73.  
  74. nameserver
  75. ----------
  76.  
  77. nameserver <ip_address>
  78.  
  79.  
  80. Internet address (in dot notation) of a name server that the resolver
  81. should query.
  82.  
  83. Up to MAXNS (currently 3) name servers may be listed, one per keyword.
  84.  
  85. If there are multiple servers, the resolver library queries them in the
  86. order listed. If no nameserver entries are present, the default is to
  87. use the name server on the local machine. (The algorithm used is to try
  88. a name server, and if the query times out, try the next, until out of
  89. name servers, then repeat trying all the name servers until a maximum
  90. number of retries are made).
  91.  
  92.  
  93. domain
  94. ------
  95.  
  96. Local domain name.
  97.  
  98. Most queries for names within this domain can use short names relative
  99. to the local domain.
  100.  
  101. If no domain entry is present, the domain is determined from the local
  102. host name returned by gethostname() the domain part is taken to be
  103. everything after the first '.'.
  104.  
  105. Finally, if the host name does not contain a domain part, the root
  106. domain is assumed.
  107.  
  108.  
  109. search
  110. ------
  111.  
  112. Search list for host-name lookup.
  113.  
  114. The search list is normally determined from the local domain name; by
  115. default, it begins with the local domain name, then successive parent
  116. domains that have at least two components in their names. This may be
  117. changed by listing the desired domain search path following the
  118. \fIsearch\fP keyword with spaces or tabs separating the names.
  119.  
  120. Most resolver queries will be attempted using each component of the
  121. search path in turn until a match is found.
  122.  
  123. Note that this process may be slow and will generate a lot of network
  124. traffic if the servers for the listed domains are not local, and that
  125. queries will time out if no server is available for one of the domains.
  126.  
  127. The search list is currently limited to six domains
  128. with a total of 256 characters.
  129.  
  130.  
  131. sortlist
  132. --------
  133.  
  134. Sortlist allows addresses returned by gethostbyname to be sorted.
  135.  
  136. A sortlist is specified by IP address netmask pairs. The netmask is
  137. optional and defaults to the natural netmask of the net. The IP address
  138. and optional network pairs are seperated by slashes. Up to 10 pairs may
  139. be specified.
  140.  
  141. e.g. sortlist 130.155.160.0/255.255.240.0 130.155.0.0
  142.  
  143.  
  144. options
  145. -------
  146.  
  147. Options allows certain internal resolver variables to be modified.
  148.  
  149. The syntax is
  150.  
  151. options <option> ...
  152.  
  153. where <option> is one of the following:
  154.  
  155. debug   sets RES_DEBUG in _res.options.
  156.  
  157. ndots   sets a threshold for the number of dots which must appear in a
  158.         name given to res_query (see resolver) before an initial
  159.         absolute query will be made.  The default for n is 1, meaning
  160.         that if there are any dots in a name, the name will be tried
  161.         first as an absolute name before any search list elements are
  162.         appended to it.
  163.  
  164.  
  165.  
  166. cachesize
  167. ---------
  168.  
  169. Enables the RR cache. Values may be given as <n> bytes, or <n>k kbytes.
  170. Size less than 1024 are rounded upto 1024.
  171.  
  172.  
  173. cacheload
  174. ---------
  175.  
  176. Read RRs from one or more file into the cache. If you are saving the
  177. cache at shutdown, then one of thes files should be the cache file.
  178.  
  179. for eg:
  180. cacheload  resboot rescache
  181.  
  182.  
  183. cachesave
  184. ---------
  185.  
  186. This sets where the cache is saved to at shutdown.
  187.  
  188.  
  189. retry
  190. -----
  191.  
  192. This sets the number of retries attempted to each nameserver (default 4)
  193.  
  194. timeout
  195. -------
  196.  
  197. This sets the min and max timeouts between retrying the same nameserver again.
  198. After each retry, the timeout is doubled upto the max value.
  199.  
  200. Nameserver retries are dstributed through the timeout period, so if the
  201. timeout period is 6 seconds, and 3 nameservers have be specified, the
  202. next nameserver is tried 2 seconds after the first.
  203.  
  204.  
  205. ----
  206.  
  207.  
  208. The domain and search keywords are mutually exclusive. If more than one
  209. instance of these keywords is present, the last instance wins.
  210.  
  211. The search keyword of a system's resolv.conf file can be overridden on a
  212. per-process basis by setting the environment variable LOCALDOMAIN to a
  213. space-separated list of search domains.
  214.  
  215. The options keyword of a system's resolv.conf file can be amended on a
  216. per-process basis by setting the environment variable RES_OPTIONS to a
  217. space-separated list of resolver options as explained above under
  218. options.
  219.  
  220. The keyword and value must appear on a single line, and the keyword
  221. (e.g. nameserver) must start the line.  The value follows the keyword,
  222. separated by white space.
  223.  
  224.  
  225. Programmer Interface
  226. ====================
  227.  
  228. This file is incomplete, there are also a few *commands, some of which
  229. are implemented.
  230.  
  231. The SWI Interface is as follows:
  232.  
  233. SWI Internet_GetHostByName &46000
  234.  
  235. On entry:
  236.   R0 = 0
  237.   R1 = -> host name
  238.  
  239. On exit:
  240.   R1 = pointer to hostent structure or NULL if not found
  241.  
  242.  
  243. SWI Internet_GetHostByAddr &46001
  244. On entry:
  245.   R0 = 0
  246.   R1 = -> host addr
  247.   R2 = len of addr
  248.   R3 = type of addr
  249.  
  250. On exit:
  251.   R1 = pointer to hostent structure, or NULL if not found
  252.  
  253. Where the hostent stucture is defined as below. Note that all addresses
  254. are given in net byte order (the reverse of the normal Acorn byte order).
  255.  
  256. struct hostent {
  257.   char *h_name;                /* Official name of host */
  258.   char **h_aliases;            /* Alternative names for host */
  259.   int  h_addrtype;             /* Host address type */
  260.   int  h_length;               /* Length of each address */
  261.   char **h_addr_list;          /* List of addresses for host */
  262. #define h_addr h_addr_list[0]  /* Address, for back compatability */
  263. };
  264.